Version: 1.7.0

TACO NN 工具链技术手册

第一部分：入门篇

1.1 TACO taNNTC 简介

1.1.1 概述

本手册旨在为开发者提供详尽的技术指导，帮助您将主流深度学习框架训练的模型高效转换、部署至 TOPSFuture EA65xx NPU 硬件平台。

TACO taNNTC 可负责将来自主流深度学习框架（如 TensorFlow、PyTorch、ONNX 等）的预训练模型，进行包括图优化、算子融合、量化（如 INT8、FP16）、编译和内存布局优化在内的一系列转换，最终生成可在 EA65xx NPU 上高效执行的二进制指令或模型格式。

1.1.2 典型部署流程

1. 模型构建

功能描述：此阶段旨在将源自主流深度学习框架（如 TensorFlow、ONNX 等）的模型，转换为可在对应平台部署的模型。该过程对输入的模型进行中间表达转化、量化、对应 NPU 图优化与代码生成，最终编译并打包成一个高度优化的可执行文件。
执行命令：convert_model build --config <config.json>
输出产物:一个二进制图文件 (.nb)，该文件是可直接在目标硬件上运行的模型文件。

2. 板端推理 (On-device Inference)

功能描述：此为最终的部署与执行环节，独立于 taNNTC 工具链。编译生成的 .nb 文件被部署到搭载 EA65 系列 NPU 的目标硬件上。而设备端的 TaRuntime 负责加载该二进制图文件，并通过 NPU 驱动执行高性能的推理计算。

3. 模型构建的中间文件说明

输出产物：模型构建完成后，生成的中间文件保存在输出目录的 acuity_temp/ 目录下
模型中间表示(IR)：以下两种文件，合称为中间表示 (IR)：
- 网络结构文件 (.json)：描述模型的拓扑结构。
- 网络权重文件 (.data)：存储模型的参数权重。
输入输出配置文件(.yml): *_inputmeta.yml 文件详细定义了模型在推理前对输入数据（如图像）的预处理步骤（例如：Resize、Crop、Normalization 等）以及对模型输出的后处理步骤（例如：解码、排序等）。这确保了后续量化、验证和最终部署时数据处理逻辑的完全一致。 postprocess_file.yml 文件设置对模型输出的处理。
- 输入端预处理文件 (*_inputmeta.yml)：定义输入数据的处理流程。
- 输出端后处理文件 (postprocess_file.yml)：定义模型输出的解析流程。
模型量化表(.quantize): 量化工具使用 IR 文件，执行模型优化并计算量化参数。该过程利用校准数据集分析张量的数据分布，从而生成最优的定点转换参数。
- 量化表文件 (.quantize): 记录了用于低精度转换的缩放因子 (scale) 和零点 (zero-point) 等关键信息。

4. (可选) PC 端推理验证 (Verification)

功能描述：此为一可选的验证与调试环节。在执行最终导出之前，可在开发主机（PC/服务器）上对量化后的模型进行推理，用于评估量化引入的精度影响，确保模型行为符合预期。
执行命令：pegasus inference ...

1.1.3 工具链特性

输入支持
- 框架模型：TensorFlow (2.3.x ~ 2.17.x)、TFLite、Caffe、ONNX (1.16.2)、PyTorch (2.3.0)、Keras、Darknet
- 数据集格式：Text / NumPy / SQLite
量化支持
- 数据类型：uint8、int8、int16、bfloat16、float16、float32
- 量化算法：KL 散度、滑动平均、自动混合精度等
输出支持
- 格式：二进制图文件 .nb

1.2 系统要求与环境安装

1.2.1 系统要求

资源	要求
CPU	Intel Core i5-6500 或以上（支持 AVX）
GPU（可选）	NVIDIA CUDA 架构显卡
RAM	≥ 8 GB
磁盘	≥ 160 GB
OS	Ubuntu 18.04 / 20.04 / 22.04 64 位
Python	3.6 / 3.8 / 3.10

1.2.2 环境安装

taNNTC 工具链通过 Docker 容器提供，可简化环境配置。

拉取 Docker 镜像

docker pull harbor.topsfuture.com:9099/mes20/ta-nntc:latest

创建并进入 Docker 容器

# 创建并后台运行容器，并将当前目录映射到容器的 /home 目录
docker run -itd --name tool_chain -v $(pwd):/home harbor.topsfuture.com:9099/mes20/ta-nntc:latest

# 启动容器（如果已停止）
docker start tool_chain

# 进入容器的交互式终端
docker exec -it tool_chain /bin/bash

第二部分：实践篇

2.1 快速入门：YOLOv11s 模型转换

本章以 YOLOv11s 模型为例，通过一个完整的端到端示例，带您体验使用 taNNTC 工具链完成模型导入、量化与导出的全过程。

2.1.1 前期准备

模型下载

⬇️ yolo11s.onnx
量化校准数据集下载

⬇️ yolo11s_calib.zip

解压后将图片存放至指定目录，用于量化校准。
配置文件下载

⬇️ config_file.zip

2.1.2 组织目录结构

在进行模型编译与量化前，建议按如下目录组织文件，便于工具链调用与管理：

project_yolo11s/

├── dataset.txt                      # 量化数据集列表文件
├── yolo11s_config.json              # 工具链配置文件
├── yolo11s.onnx                     # 源 ONNX 模型文件
└── val2017_1000/                    # 量化校准数据集
    ├── 0000000000.jpg
    ├── 0000000001.jpg
    ├── 0000000002.jpg
    └── ...

说明：taNNTC 支持通过文本配置文件指定模型的输入和输出节点。如果不进行配置，系统将自动识别模型的 I/O 节点（适用于默认全模型量化）。以 YOLOv11s 为例：

输入节点
- images
输出节点
- /model.23/Reshape_output_0
- /model.23/Reshape_1_output_0
- /model.23/Reshape_2_output_0

2.1.3 输出说明

YOLOv11s 的三个输出对应三个不同尺度的特征图（stride = 8、16、32）。每个预测点都会输出一个 144 维向量，其中包含边界框和分类信息。

144 维向量的组成：
- 前 64 维：边界框回归信息（采用 DFL 分布形式，对 x、y、w、h 各 16 个 bin 编码）。
- 后 80 维：类别置信度（每个通道对应一个类别，已融合 objectness 概念）。
第三维度（6400 / 1600 / 400）：表示该尺度下的网格点数
- [1,144,6400] → 对应 80×80 特征图（小目标）
- [1,144,1600] → 对应 40×40 特征图（中目标）
- [1,144,400] → 对应 20×20 特征图（大目标）

量化数据集：工具链支持以文本格式指定量化数据集路径文件 dataset.txt，文件格式如下：

val2017_1000/0000000000.jpg
val2017_1000/0000000001.jpg
val2017_1000/0000000002.jpg
...

每行对应一张图片的相对路径或绝对路径。
建议数据集涵盖多种场景、光照和角度，以提升量化精度。
数据集规模通常建议在 100~1000 张之间，根据模型大小和精度需求调整。

下载的 config_file 目录下包含一个示例配置文件 dataset.txt，可以直接使用。

2.1.4 模型编译与量化

进入 project_yolo11s/ 目录，打开 yolo11s_config.json 文件，进行工具链配置。

生成 FP16 模型

在 yolo11s_config.json 文件中找到 quantize 段，修改如下：

    "quantize": {
      "qtype": "float16",
      "dataset_file_type": "TEXT",
      "dataset_file": "./dataset.txt"
    },

生成 INT8 模型

在 yolo11s_config.json 文件中找到 quantize 段，修改如下：

    "quantize": {
      "qtype": "int8",
      "dataset_file_type": "TEXT",
      "dataset_file": "./dataset.txt",
      "input_num": 25
    },

执行下列命令生成可在 EA65 系列 NPU 上运行的 .nb 格式模型。

convert_model build --config yolo11s_config.json

执行成功后，最终用于板端部署的文件将位于 output/ 目录下，名为 yolo11s_int8.nb。

2.1.5 工具解析：从示例到实践

我们提供的 convert_model 工具是实现模型一键式编译与量化的便捷工具，需要配合 JSON 配置文件使用。为了帮助您更好地理解其工作原理，并能根据自身需求进行灵活配置，本节将对 convert_model 工具的核心命令进行分步解析。

因此，您可以将此 sample 视为一个最佳实践模板。配置文件中的每一个字段都由一系列参数构成，这些参数的具体含义和更多用法，均可在「TACO NN 工具链技术手册」文档的「参数篇」章节中查阅。

convert_model 工具的核心流程主要分为三个阶段：模型导入、生成配置文件、模型量化和模型导出。

阶段一：模型导入 (Import)

将 ONNX 模型转换为 taNNTC 的中间表示 (IR)。

// .json 中的参数
    "import" : {
      "name": "yolo11s",
      "framework":  "ONNX",
      "onnx_model": "./yolo11s.onnx",
      "inputs": "images",
      "outputs": "/model.23/Reshape_output_0 /model.23/Reshape_1_output_0 /model.23/Reshape_2_output_0",
      "input-size-list": "1,3,640,640"
    },

关键参数说明：
- framework：指定当前执行的是 "ONNX 模型导入" 任务。
- onnx_model：指定输入的源 ONNX 模型文件路径。
- inputs: ONNX 模型文件的输入名
- outputs: ONNX 模型文件的输出名
- input-size-list：ONNX 模型文件的输入 tensor shape

阶段二：生成配置文件 (Generate)

此步骤基于导入后的模型结构，生成预处理和后处理的 .yml 配置文件模板。

// 1. 生成输入端预处理配置
  
    "preprocess": [{
      "reverse_channel": false,
      "mean": [0, 0, 0],
      "std": [1.0, 1.0, 1.0],
      "scale": 0.00392156,
      "add_preprocess_node": false
      }
    ],

// 2. 生成输出端后处理配置
    "postprocess": [
      {
        "add_postprocess_node": false,
        "permute": [0,1,2,3],
        "float32_out": false
      },
      {
        "add_postprocess_node": false,
        "permute": [0,1,2,3],
        "float32_out": false
      },
      {
        "add_postprocess_node": false,
        "permute": [0,1,2,3],
        "float32_out": false
      }
    ],

📝 说明：

默认生成的 .yml 文件包含默认参数，需要根据模型需求进行修改。

针对 YOLOv11s 这个模型来说，此处完成了两个关键修改：

    // 将 reverse_channel 从 true 修改为 false
      "reverse_channel": false,

    // 将 scale 值从 1.0 修改为 1/255 (0.003921569)
      "scale": 0.00392156,

关闭通道反转：因为 YOLOv11s 模型训练时使用的就是 RGB 格式的输入。
设置归一化系数：将输入图像的像素值从 [0, 255] 范围归一化到 [0, 1] 范围。

对于您自己的模型，您需要根据实际的预处理逻辑，手动或通过脚本修改这一部分。

阶段三：模型量化 (Quantize)

利用校准数据集生成量化参数。

    "quantize": {
      "qtype": "int8",
      "dataset_file_type": "TEXT",
      "dataset_file": "./dataset.txt",
      "input_num": 25
    },

命令解析：
- qtype：定义量化目标数据类型（int8）。
- dataset_file：数据集文件的路径（此处使用 TEXT 格式，.txt 文件中是数据的路径）。
- input_num：指定用于量化的数据数量。

阶段四：模型导出 (Export)

最后一步，将量化后的模型编译并打包成 NPU 可直接加载执行的二进制文件 (.nb)。

    "export": {
      "core_number": 1
    }

命令解析：
- core_number: 依据本次脚本导出来的模型为单 core 模型。

通过以上解析，可以看到，一个完整的模型部署流程是如何通过组合各阶段的参数来实现。当需要处理自己的模型时，可以以此脚本为基础，参考「TACO NN 工具链技术手册」文档的「第三部分：参数篇」章节的内容，调整各项参数，以满足特定需求。

2.2 高级专题：混合量化（Hybrid Quantization）

2.2.1 概述与原理

混合量化是一种在精度和性能之间取得更优平衡的策略。其核心思想是：对模型中大部分层使用 INT8/UINT8 高性能定点量化，同时对少数对精度非常敏感的层保留 FP16 半精度浮点计算，从而在保持高精度的同时获得显著的性能提升。

INT8 量化：将权重和激活映射到 8 位整数，运算效率高，模型体积小，但量化误差可能导致精度下降。
FP16 保留：对于量化敏感的层（如首尾卷积层、特征融合层等），直接使用 FP16 存储和计算，减少精度损失。
混合调度：在推理引擎中，INT8 与 FP16 层可以混合执行，由硬件调度自动完成数据格式的转换与传递。

2.2.2 混合量化流程

在 output/acuity_temp/ 目录下找到模型的中间文件：

tree 
.
├── model.data                    # 模型权重文件
├── model_inputmeta.yml           # 模型前处理配置文件
├── model_int8.quantize           # 模型量化文件
├── model.json                    # 模型结构文件
└── model_postprocess_file.yml    # 模型后处理文件

可将他们更名为 yolo11s_*，后续所有操作均使用更名后的文件，具体更名清单如下：

tree 
.
├── yolo11s.data                    # 模型权重文件
├── yolo11s_inputmeta.yml           # 模型前处理配置文件
├── yolo11s_int8.quantize           # 模型量化文件
├── yolo11s.json                    # 模型结构文件
└── yolo11s_postprocess_file.yml    # 模型后处理文件

步骤 1：搜索敏感层

通过在量化命令中加入特定参数，可以分析每一层在量化过程中的精度损失（熵值），使用下面的命令生成 entropy.txt ：

pegasus quantize  \
--model yolo11s.json \
--model-data yolo11s.data \
--model-quantize yolo11s_int8.quantize \
--quantizer asymmetric_affine \
--qtype 'int8' \
--with-input-meta yolo11s_inputmeta.yml \
--rebuild \
--compute-entropy

该命令执行后，会生成模型的量化结果文件 yolo11s_int8.quantize （记录每一层的量化参数）以及熵值文件 entropy.txt。熵值取 0～1 之间，数值越接近 1 表示该层量化精度越低，也即损失越大。 .quantize 文件中的末尾 customized_quantize_layers 字段，是推荐进行混合量化的层。你可以不做修改进行混合量化，也可按照步骤2的流程手动配置。

步骤 2：手动配置高精度层 (可选)

根据 entropy.txt 的分析结果，打开 .quantize 配置文件（如 yolo11s_int8.quantize），找到 customized_quantize_layers 字段，将熵值较高的敏感层（例如 > 0.6）添加进去，并指定其使用高精度格式。这里我们以 yolo11s 为例，手动配置混合量化层：

打开 yolo11s_int8.quantize 文件，找到 customized_quantize_layers 字段，将 entropy.txt 中熵值大于 0.6 的层添加到该字段中，如：

  model.23/cv3.2/cv3.2.0/cv3.2.0.1/conv/Conv_output_0_59: dynamic_fixed_point-i16
  model.23/cv3.1/cv3.1.0/cv3.1.0.1/conv/Conv_output_0_63: dynamic_fixed_point-i16
  model.2/m.0/cv1/conv/Conv_output_0_230: dynamic_fixed_point-i16
  model.0/conv/Conv_output_0_265: dynamic_fixed_point-i16
  model.23/cv3.1/cv3.1.1/cv3.1.1.0/conv/Conv_output_0_51: dynamic_fixed_point-i16
  model.23/cv2.2/cv2.2.0/conv/Conv_output_0_45: dynamic_fixed_point-i16
  model.23/cv2.1/cv2.1.0/conv/Conv_output_0_49: dynamic_fixed_point-i16
  model.1/conv/Conv_output_0_259: dynamic_fixed_point-i16
  model.23/cv3.0/cv3.0.1/cv3.0.1.0/conv/Conv_output_0_55: dynamic_fixed_point-i16
  model.2/cv1/conv/Conv_output_0_247: dynamic_fixed_point-i16
  model.23/cv2.0/cv2.0.2/Conv_output_0_13: dynamic_fixed_point-i16
  model.23/cv2.1/cv2.1.2/Conv_output_0_11: dynamic_fixed_point-i16
  model.23/cv2.0/cv2.0.1/conv/Conv_output_0_29: dynamic_fixed_point-i16
  model.10/m/m.0/attn/pe/conv/Conv_output_0_176: dynamic_fixed_point-i16
  model.23/cv2.2/cv2.2.2/Conv_output_0_9: dynamic_fixed_point-i16
  model.23/cv2.1/cv2.1.1/conv/Conv_output_0_25: dynamic_fixed_point-i16
  model.23/cv2.2/cv2.2.1/conv/Conv_output_0_21: dynamic_fixed_point-i16

做上述修改的时候，由于 .quantize 文件将按照 yaml 格式解析，注意缩进。

步骤 3：执行混合量化并导出

首先，使用 --hybrid 标记执行量化，生成混合量化配置。

pegasus quantize  \
--model yolo11s.json \
--model-data yolo11s.data \
--quantizer asymmetric_affine \
--qtype 'int8' \
--with-input-meta yolo11s_inputmeta.yml \
--model-quantize  yolo11s_int8.quantize \
--hybrid

这会生成一个新的 yolo11s_int8.quantize.json 文件。然后，使用这个新文件作为 --model 参数来导出最终的混合量化模型。

pegasus export ovxlib \
--model         yolo11s_int8.quantize.json \
--model-data    yolo11s.data \
--dtype  quantized \
--model-quantize   yolo11s_int8.quantize \
--target-ide-project    'linux64' \
--with-input-meta       yolo11s_inputmeta.yml \
--postprocess-file      yolo11s_postprocess_file.yml \
--output-path           export/yolo11s_hybrid \
--pack-nbg-unify \
--viv-sdk  '/usr/src/vSimulator/x86_64_linux' \
--optimize VIP9200O_PID0X10000049

2.2.3 精度与性能分析

精度测算：可根据 Model Zoo 中提供的标准方式进行精度测试，对比混合量化模型与原模型的差异。
精度问题排查：
层级性能分析：在板端使用 vpm_run 命令执行模型时，附加 -cnnprofile_level 2 参数，即可获取每一层的详细性能分析报告。

第三部分：参数篇

3.1 JSON 配置文件参数详解

本章节详细列出了 covnert_model 工具在各个核心阶段（导入、量化、推理、导出）所使用的参数。

3.2 模型导入 (Import)

目标：此为工具链的第一步，旨在将一个由主流框架（如 TensorFlow、ONNX、Caffe）训练生成的模型，解析并转换为 taNNTC 工具链专用的中间表示 (IR) 格式。

输入：原始模型文件（例如 .onnx、.pb、.tflite 文件）。

输出：一个 .json 文件（描述网络结构）和一个 .data 文件（存储网络权重）。这对文件是后续所有操作的基础。

在 import 字段支持下列参数配置：

参数	含义	类型 / 可选值	默认值	示例
`name`	模型通用名称，用于命名输出文件	`str`	`model`	`"name": "yolo11s"`
`framework`	导入模型的原框架	`ONNX / Caffe / TensorFlow /...`	—	`"framework": "ONNX"`
`inputs`	模型输入节点名（空格分隔多个）	`str list`	框架可自动识别时可省略	`"inputs": "images"`
`input-size-list`	各输入张量形状，多个输入间用 `#` 分隔	`str`	自动推断（支持时）	`"input-size-list": "1,3,640,640"`
`outputs`	模型输出节点名（空格分隔多个）	`str list`	自动识别（支持时）	`"outputs": "out0 out1 out2"`
`onnx_model`	(ONNX) 待导入的源模型文件路径	`str`	—	`"onnx_model": "./yolo11s.onnx"`
`input-dtype-list`	(ONNX) 各输入数据类型	`float/int8/uint8/int16/…`	`float`	`"input-dtype-list": "float"`
`proto`	(Caffe) 待导入的模型文件协议	`caffe / lstm_caffe / ...`	—	`"proto": "caffe"`
`caffemodel`	(Caffe) .caffemodel 文件路径	`str`	—	`"caffemodel": "mobilenet.caffemodel"`
`protobuf_file`	(TensorFlow) .pb 模型文件路径	`str`	—	`"protobuf_file": "frozen_graph.pb"`
`mean_values`	(TensorFlow) 输入均值	`float[,float...]`	—	`"mean_values": "0.0,0.0,0.0"`
`std_values`	(TensorFlow) 输入标准差	`float[,float...]`	—	`"std_values": "255.0,255.0,255.0"`
`predef_file`	(TensorFlow) 预定义 `.npz`（占位符/阶段开关等）	`str`	—	`"predef_file": "flags.npz"`
`subgraphs`	(TensorFlow) 指定子图的输入/输出列表	`str`	—	`"subgraphs": "in1#out1;in2#out2"`
`tflite_file`	(TFLite) .tflite 模型文件路径	`str`	—	`"tflite_file": "mobilenet.tflite"`
`cfg_file`	(Darknet) .cfg 模型文件路径	`str`	—	`"cfg_file": "yolo.cfg`
`weights_file`	(Darknet) .weights 文件路径	`str`	—	`"weights_file": yolo.weights`
`pytorch_file`	(PyTorch) .pt 模型文件路径	`str`	—	`"pytorch_file": "alexnet.pt"`
`config`	(PyTorch) 导入配置文件路径（pytorch 框架专用）	`str`	—	`"config": "import_cfg.json"`
`keras_file`	(Keras) .h5 模型文件路径	`str`	—	`"keras_file": "mobilenet.h5"`

3.3 前后处理配置文件的参数说明

yml 文件用法：工具会基于已导入的模型结构（.json 文件），自动生成预处理和后处理配置文件的模板（.yml 文件），用户只需根据模型所需，修改少量参数或不作修改。可以直接修改 .yml 文件，再进行模型导出(convert_model export)，也可以在 .json 文件中配置要修改的参数。

目前 preprocess 字段支持的参数如下，工具会根据此字段参数修改 model_inputmeta.yml 文件：

参数	含义	类型 / 可选值	默认值	示例
`reverse_channel`	翻转输入 tensor 的通道顺序	`bool`	`false`	`"reverse_channel": true`
`mean`	预处理中归一化使用的均值 (值域[0,1])	`arr`	—	`"mean": [0, 0, 0]`
`std`	预处理中归一化使用的std值 (值域[0,1])	`arr`	—	`"std": [1.0, 1.0, 1.0]`
`scale`	预处理中归一化使用的scale值	`float`	—	`"scale": 0.00392156`
`add_preprocess_node`	向导出的网络添加前处理节点	bool	`false`	`"add_preprocess_node": false`

目前 postprocess 字段支持的参数如下，工具会根据此字段参数修改 postprocess.yml 文件：

参数	含义	类型 / 可选值	默认值	示例
`add_postprocess_node`	是否向导出的网络添加后处理节点	`bool`	`false`	`"add_postprocess_node": false`
`premute`	指定维度顺序，重新排列输出张量的维度	`arr`	—	`"permute": [0,1,2,3]`
`float32_out`	将输出张量转换为 float32 数据类型	`false`	—	`"float32_out": false`

3.3.1 **`*_inputmeta.yml`** 前处理配置文件内容详解

此文件用于配置模型输入端的预处理。

常见配置：
- mean、scale：设置归一化的均值和缩放系数。
- reverse_channel：BGR 与 RGB 通道反转开关。工具链将图片解码后按 RGB 顺序输入网络。如果目标网络默认的 channel 顺序是 BGR，则此处需要将此项设为 true。若不需要反转通道，则设为 false。
高级用法（指定输入格式）：如果希望模型直接接收 RGB_PACKED 或 NV12 等特定硬件格式的数据，并让 NPU 执行预处理，需要修改：
```
add_preproc_node: true
preproc_type: IMAGE_NV12 # (或其他格式)
```

3.3.2 **`*_postprocess_file.yml`** 后处理配置文件内容详解

此文件用于配置模型输出端的后处理。

常见用法（强制输出为 Float32）：默认情况下，模型输出的数据类型与量化类型一致。如果希望无论量化类型是什么，最终输出都是 Float32，需要对每个输出层进行如下配置：

postprocess:
app_postprocs: # 该部分配置会影响最终导出的模型
- lid: output_0 # 替换为您的输出层名称
postproc_params:
add_postproc_node: true
force_float32: true # 强制输出为 float32
# 如果有多个输出层，在此继续添加
- lid: output_1
postproc_params:
# ...

3.4 模型量化 (Quantize)

目标：此为关键的优化步骤，旨在通过降低模型的数据精度（例如从 FP32 转换为 INT8），来减小模型体积、降低内存占用，并利用 NPU 的定点运算单元实现显著的推理加速。

输入：上一阶段生成的 .json 和 .data 文件，以及一个用于校准的样本数据集。

输出：一个 .quantize 文件，其中包含了每一层的量化参数（如缩放因子、零点等）。

在 quantize 字段支持下列参数配置：

参数	含义	类型 / 可选值	默认值	示例
`qtype`	目标精度类型	`uint8 / int8 / int16 / bfloat16 / float16 / …`	`uint8`	`"qtype": "uint8"`
`dataset_file_type`	描述数据集文件的类型	`TEXT / NPY`	`TEXT`	`"dataset_file_type":"TEXT"`
`dataset_file`	量化数据集列表文件（每行一张图片路径）	`str`	—	`"dataset_file": "./dataset.txt"`
`input_num`	校准次数	`int`	`1`	`"input_num": 25`

3.5 模型导出 (Export)

目标：此为工具链的最后一步，旨在将中间表示 (IR) 和量化结果，编译并打包成一个专为目标 NPU 硬件优化、可直接部署执行的最终产物。

输入：.json、.data 文件以及（若为量化模型）.quantize 文件。

输出：一个或多个可直接在板端运行的文件，最核心的是统一的二进制图文件（例如 .nb）。

在 export 字段支持下列参数配置：

参数	含义	类型 / 可选值	默认值	示例
`core_number`	目标硬件上的核心使用数量	`1 / 2`	—	`"core_number": 1`

3.6 模型推理 (Inference)

目标：此模块使用 pegasus 命令行工具，用于在 开发主机（PC/服务器） 上模拟模型的推理过程，主要用于功能验证和精度评估。您可以在部署到硬件之前，用它来快速验证原始浮点模型的正确性，或评估量化后模型的精度损失情况。

输入：.json 和 .data 文件，（若评估量化模型）还需 .quantize 文件。

输出：模型的推理结果，可用于与基准值 (Golden) 进行比对。

参数	含义	类型 / 可选值	默认值	示例
`--model`	推理用 `.json`	`str`	—	`--model y11.json`
`--model-data`	推理用 `.data`	`str`	—	`--model-data y11.data`
`--model-quantize`	推理用 `.quantize`（选择量化推理时）	`str`	—	`--model-quantize y11.quantize`
`--with-input-meta`	输入元数据 `.yml`	`str`	—	`--with-input-meta inputmeta.yml`
`--dtype`	推理精度	`float32 / quantized`	`float32`	`--dtype quantized`
`--batch-size`	推理批大小	`int`	由输入元数据推断	`--batch-size 1`
`--iterations`	推理批次数	`int`	`1`	`--iterations 100`
`--device`	推理计算设备	`GPU/CPU`	`GPU`	`--device GPU`
`--postprocess`	内置后处理任务	`print_topn / dump_result / classification_validate / detection_validate / …`	`classification_classic`	`--postprocess detection_validate`
`--postprocess-file`	自定义后处理 `.yml`	`str`	—	`--postprocess-file post.yml`
`--output-dir`	推理结果输出目录	`str`	当前目录/控制台	`--output-dir outputs/`

附录 A：备注与说明

1. 关于混合量化

该功能通常配合 --hybrid, --algorithm auto, --compute-entropy 等参数共同使用，以自动或半自动方式定位敏感层，并通过修改 .quantize 文件来指定保留高精度的层。

2. 关于版本差异

不同版本的工具链在少量参数名称或默认值上可能存在差异，建议以当前环境的 pegasus <command> --help 输出为最准确的参考。

3. 配置单核与双核模型编译

通过组合使用 VIV_MGPU_AFFINITY 和 VIV_OVX_MULTI_DEVICE 环境变量，可以控制导出的 .nb 文件在目标硬件上的核心使用方式。

3.1 导出单核模型（推荐）

这是最常用且推荐的模式，将模型编译为在单个NPU核心上运行。导出 NBG 文件之前，在环境中添加如下环境变量：

# 编译单core模型的环境变量
export VIV_MGPU_AFFINITY=1:0 
export VIV_OVX_MULTI_DEVICE=1:1

或者在 .json 配置文件的 export 字段配置 core_number 参数：

    "export": {
      "core_number": 1
    }

3.2 导出双核模型

对于较大的模型，可以尝试编译为在双NPU核心上并行运行的模式，以可能获得更高的性能。导出 NBG 文件之前，在环境中添加如下环境变量：

# 编译双 core 模型
export VIV_MGPU_AFFINITY=1:0
export VIV_OVX_MULTI_DEVICE=0:2

或者在 .json 配置文件的 export 字段配置 core_number 参数：

    "export": {
      "core_number": 2
    }

第一部分：入门篇​

1.1 TACO taNNTC 简介​

1.1.1 概述​

1.1.2 典型部署流程​

1.1.3 工具链特性​

1.2 系统要求与环境安装​

1.2.1 系统要求​

1.2.2 环境安装​

第二部分：实践篇​

2.1 快速入门：YOLOv11s 模型转换​

2.1.1 前期准备​

2.1.2 组织目录结构​

2.1.3 输出说明​

2.1.4 模型编译与量化​

2.1.5 工具解析：从示例到实践​

2.2 高级专题：混合量化（Hybrid Quantization）​

2.2.1 概述与原理​

2.2.2 混合量化流程​

步骤 1：搜索敏感层​

步骤 2：手动配置高精度层 (可选)​

步骤 3：执行混合量化并导出​

2.2.3 精度与性能分析​

第三部分：参数篇​

3.1 JSON 配置文件参数详解​

3.2 模型导入 (Import)​

3.3 前后处理配置文件的参数说明​

3.3.1 *_inputmeta.yml 前处理配置文件内容详解​

3.3.2 *_postprocess_file.yml 后处理配置文件内容详解​

3.4 模型量化 (Quantize)​

3.5 模型导出 (Export)​

3.6 模型推理 (Inference)​

附录 A：备注与说明​

1. 关于混合量化​

2. 关于版本差异​

3. 配置单核与双核模型编译​

3.1 导出单核模型（推荐）​

3.2 导出双核模型​